<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>PowerVR SDK</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
<table width="100%">
  <tr>
    <td width="33%">
      <p align="left">&nbsp;<a href="http://www.imgtec.com"><img border="0" src="IMGLogo.jpg" width="200" height="30"></a></p>
    </td>
    <td width="33%">
      <p align="center"><font color="#808080" face="Arial" size="2">PowerVR Software Development Kit</a></font></p>
    </td>
    <td width="34%">
      <p align="right"><a href="http://www.powervr.com"><img border="0" src="PVRlogo.jpg" width="200" height="27"></a></p>
    </td>
  </tr>
</table>
<hr>
</head><body>
<!-- Generated by Doxygen 1.3.6 -->
<div class="qindex"><a class="qindexHL" href="index.html">Main&nbsp;Page</a> | <a class="qindex" href="hierarchy.html">Class&nbsp;Hierarchy</a> | <a class="qindex" href="annotated.html">Class&nbsp;List</a> | <a class="qindex" href="files.html">File&nbsp;List</a> | <a class="qindex" href="functions.html">Class&nbsp;Members</a> | <a class="qindex" href="globals.html">File&nbsp;Members</a></div>
<h1><a class="el" href="classPVRShell.html">PVRShell</a> </h1>
<p>
<h2><a class="anchor" name="_a_">
Overview</a></h2>
<a class="el" href="classPVRShell.html">PVRShell</a> is a C++ class used to make programming for PowerVR platforms easier and more portable. <a class="el" href="classPVRShell.html">PVRShell</a> takes care of all API and OS initialisation for the user and handles adapters, devices, screen/windows modes, resolution, buffering, depth-buffer, viewport creation &amp; clearing, etc...<p>
<a class="el" href="classPVRShell.html">PVRShell</a> consists of 3 files: <a class="el" href="PVRShell_8cpp.html">PVRShell.cpp</a>, <a class="el" href="PVRShellOS_8cpp.html">PVRShellOS.cpp</a> and <a class="el" href="PVRShellAPI_8cpp.html">PVRShellAPI.cpp</a>.<p>
<a class="el" href="PVRShellOS_8cpp.html">PVRShellOS.cpp</a> and <a class="el" href="PVRShellAPI_8cpp.html">PVRShellAPI.cpp</a> are supplied per platform and contain all the code to initialise the specific API (OpenGL ES, Direct3D Mobile, etc.) and the OS (Windows, Linux, WinCE, etc.). <a class="el" href="PVRShell_8cpp.html">PVRShell.cpp</a> is where the common code resides and it interacts with the user application through an abstraction layer.<p>
A new application must link to these three files and must create a class that will inherit the <a class="el" href="classPVRShell.html">PVRShell</a> class. This class will provide five virtual functions to interface with the user.<p>
The user also needs to register his application class through the NewDemo function:<p>
<pre class="fragment"><div><span class="keyword">class </span>MyApplication: <span class="keyword">public</span> <a class="code" href="classPVRShell.html">PVRShell</a>
{
<span class="keyword">public</span>:
    <span class="keyword">virtual</span> <span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a2">InitApplication</a>();
    <span class="keyword">virtual</span> <span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a4">InitView</a>();
    <span class="keyword">virtual</span> <span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a5">ReleaseView</a>();
    <span class="keyword">virtual</span> <span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a3">QuitApplication</a>();
    <span class="keyword">virtual</span> <span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a6">RenderScene</a>();
};

<a class="code" href="classPVRShell.html">PVRShell</a>* <a class="code" href="PVRShell_8h.html#a71">NewDemo</a>()
{
    <span class="keywordflow">return</span> <span class="keyword">new</span> <a class="code" href="classMyApplication.html">MyApplication</a>();
}
</div></pre><h2><a class="anchor" name="_b_">
Interface</a></h2>
There are two functions for initialisation, two functions to release allocated resources and a render function:<p>
InitApplication() will be called by <a class="el" href="classPVRShell.html">PVRShell</a> once per run, before the graphic context is created. It is used to initialise variables that are not dependant on the rendering context (e.g. external modules, loading user data, etc.). QuitApplication() will be called by <a class="el" href="classPVRShell.html">PVRShell</a> once per run, just before exiting the program. If the graphic context is lost, QuitApplication() will not be called.<p>
InitView() will be called by <a class="el" href="classPVRShell.html">PVRShell</a> upon creation or change in the rendering context. It is used to initialise variables that are dependant on the rendering context (e.g. textures, vertex buffers, etc.). ReleaseView() will be called by <a class="el" href="classPVRShell.html">PVRShell</a> before changing to a new rendering context or when finalising the application (before calling QuitApplication).<p>
RenderScene() is the main rendering loop function of the program. This function must return FALSE when the user wants to terminate the application. <a class="el" href="classPVRShell.html">PVRShell</a> will call this function every frame and will manage relevant OS events.<p>
There are other <a class="el" href="classPVRShell.html">PVRShell</a> functions which allow the user to set his preferences and get data back from the devices:<p>
PVRShellSet() and PVRShellGet() are used to pass data to and from <a class="el" href="classPVRShell.html">PVRShell</a>. PVRShellSet() is recommended to be used in InitApplication() so the user preferences are applied at the API initialisation. There is a definition of these functions per type of data passed or returned. Please check the prefNameBoolEnum, prefNameFloatEnum, prefNameIntEnum, prefNamePtrEnum and prefNameConstPtrEnum enumerations for a full list of the data available.<p>
This is an example:<p>
<pre class="fragment"><div><span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a2">MyApplication::InitApplication</a>()
{
    <a class="code" href="classPVRShell.html#a7">PVRShellSet</a> (prefFullScreen, <span class="keyword">true</span>);
}

<span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a6">MyApplication::RenderScene</a>()
{
    <span class="keywordtype">int</span> dwCurrentWidth = <a class="code" href="classPVRShell.html#a12">PVRShellGet</a> (prefHeight);
    <span class="keywordtype">int</span> dwCurrentHeight = <a class="code" href="classPVRShell.html#a12">PVRShellGet</a> (prefWidth);

    <span class="keywordflow">return</span> <span class="keyword">true</span>;
}
</div></pre><h2><a class="anchor" name="_c_">
Helper functions</a></h2>
The user input is abstracted with the PVRShellIsKeyPressed() function. It will not work in all devices, but we have tried to map the most relevant keys when possible. See PVRShellKeyName enumeration for the list of keys supported. This function will return true or false depending on the specified key being pressed.<p>
There are a few other helper functions supplied by <a class="el" href="classPVRShell.html">PVRShell</a> as well. These functions allow you to read the timer, to output debug information and to save a screen-shot of the current frame:<p>
PVRShellGetTime() returns time in milliseconds.<p>
PVRShellOutputDebug() will write a debug string (same format as printf) to the platform debug output.<p>
PVRShellScreenCaptureBuffer() and PVRShellWriteBMPFile() will be used to save the current frame as a BMP file. PVRShellScreenCaptureBuffer() receives a pointer to an area of memory containing the screen buffer. The memory should be freed with free() when not needed any longer.<p>
Example of screenshot:<p>
<pre class="fragment"><div><span class="keywordtype">bool</span> <a class="code" href="classPVRShell.html#a6">MyApplication::RenderScene</a>()
{
    [...]

    <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *pLines;

    <a class="code" href="classPVRShell.html#a17">PVRShellScreenCaptureBuffer</a>(PVRShellGet (prefWidth), PVRShellGet (prefHeight), &amp;pLines);

    <a class="code" href="classPVRShell.html#a18">PVRShellScreenSave</a>(<span class="stringliteral">"myfile"</span>, pLines, NULL);

    free (pLines);

    <span class="keywordflow">return</span> <span class="keyword">true</span>;
}
</div></pre><h2><a class="anchor" name="_d_">
Command-line</a></h2>
Across all platforms, <a class="el" href="classPVRShell.html">PVRShell</a> takes a set of command-line arguments which allow things like the position and size of the demo to be controlled. The list below shows these options.<p>
<b>-width=N</b> Sets the horizontal viewport width to N.<p>
<b>-height=N</b> Sets the vertical viewport height to N.<p>
<b>-posx=N</b> Sets the x coordinate of the viewport.<p>
<b>-posy=N</b> Sets the y coordinate of the viewport.<p>
<b>-FSAAMode=N</b> Sets full screen antialiasing. N can be: 0=No AA , 1=2x AA , 2=4x AA.<p>
<b>-fullscreen=N</b> Enable/Disable fullscreen mode. N can be: 0=Windowed 1=Fullscreen.<p>
<b>-qat=N</b> Quits after N seconds.<p>
<b>-qaf=N</b> Quits after N frames.<p>
<b>-powersaving=N</b> Where available enable/disable power saving. N can be: 0=Disable power saving 1=Enable power saving.<p>
<b>-vsync=N</b> Where available modify the apps vsync parameters.<p>
<b>-version</b> Output the SDK version to the debug output.<p>
<b>-info</b> Output setup information (e.g. window width) to the debug output.<p>
<b>-rotatekeys=N</b> Sets the orientation of the keyboard input. N can be: 0-3, 0 is no rotation.<p>
<b>-c=N</b> Save a single screenshot or a range. e.g. -c=1-10, -c=14.<p>
<b>-priority=N</b> EGL only. Sets the priority of the EGL context.<p>
<b>-colourbpp=N</b> EGL only. When choosing an EGL config N will be used as the value for EGL_BUFFER_SIZE.<p>
<b>-depthbpp=N</b> EGL only. When choosing an EGL config N will be used as the value for EGL_DEPTH_SIZE.<p>
<b>-config=N</b> EGL only. Force the shell to use the EGL config with ID N.<p>
Example: <pre class="fragment"><div>    Demo -width=160 -height=120 -qaf=300
</div></pre><br>
<br>
<P align=left><FONT size=2><STRONG><A 
   href="http://www.imgtec.com/powervr/insider/legal/index.asp">Copyright</A> � 
   1999-2008, Imagination Technologies Ltd.</STRONG></FONT></P>
<hr>
<address style="align: left;"><small><FONT color=f0f>
Generated by <a href="http://www.doxygen.org/index.html">DOXYGEN</a> 1.3.6</small></address>
</body>
</html>
